package com.rcpcompany.ui.flows;

import java.util.Set;

import org.eclipse.jface.operation.IRunnableContext;
import org.eclipse.swt.widgets.Button;
import org.eclipse.ui.IViewPart;
import org.eclipse.ui.IWorkbenchPartSite;

/**
 * The interface for a container that holds a set of {@link IFlowDirector flow
 * directors}.
 * <p>
 * The implementation ({@link FlowView}) is a {@link IViewPart} that can handle
 * a number of concurrent flows.
 * <p>
 * 
 * @author Tonny Madsen, The RCP Company
 */
public interface IFlowContainer extends IRunnableContext {
	/**
	 * Opens and shows a director in this container. If the director is already
	 * opened, then the director is shown again the same state as when last
	 * shown.
	 * 
	 * @param director
	 *            the director to show
	 */
	public void openDirector(IFlowDirector director);

	/**
	 * Closes an existing open director.
	 * <p>
	 * All open pages of the director is first disposed.
	 * <p>
	 * If the director was the current director, then the next director is
	 * automatically opened, if any.
	 * 
	 * @param director
	 *            the director to close
	 */
	public void closeDirector(IFlowDirector director);

	/**
	 * Closes all currently open directors.
	 */
	public void closeAllOpenDirectors();
	
	/**
	 * Adds a new listener to the flow container.
	 * 
	 * @param listener
	 *            the new listener
	 */
	public void addListener(IFlowContainerListener listener);

	/**
	 * Removes an existing listener from the flow container.
	 * 
	 * @param listener
	 *            the existing listener
	 */
	public void removeListener(IFlowContainerListener listener);

	/**
	 * Returns the set of open directors.
	 * 
	 * @return the set
	 */
	public Set<IFlowDirector> getOpenDirectors();

	/**
	 * Returns the current director if any.
	 * 
	 * @return the director.
	 */
	public IFlowDirector getCurrentDirector();

	/**
	 * Returns the current page if any.
	 * 
	 * @return the page
	 */
	public IFlowPage getCurrentPage();

	/**
	 * Signals to the container that the specified page has been updated.
	 * <p>
	 * The container will update all parts of the interface that depends on the
	 * state of the current page - such as the "Previous", "Next" buttons...
	 * 
	 * @param page
	 *            the changed page
	 */
	public void pageUpdated(IFlowPage page);

	/**
	 * Adds a new button to the container for the current director.
	 * <p>
	 * The caller is free to add listeners to the returned button.
	 * 
	 * @param text
	 *            the text to use in the button
	 * 
	 * @return the created button
	 */
	public Button addButton(String text);

	/**
	 * Returns the site for this container. The site can be <code>null</code>.
	 * 
	 * @return the part site or <code>null</code>
	 */
	public IWorkbenchPartSite getSite();
}
